---
title: Connecting to Elasticsearch
description: How to connect to Elasticsearch with Searchkit
---

import { Callout } from "nextra-theme-docs";

# Setup & Connect to Elasticsearch

The easiest way to connect to Elasticsearch is to use Elastic cloud. You can sign up for a free trial account and get started right away.

### Using Docker

If you are using Docker, you can run Elasticsearch with the following command:

Pull the Elasticsearch Docker image:

```bash
docker pull docker.elastic.co/elasticsearch/elasticsearch:8.6.2
```

Create a docker network for Elastic:

```bash
docker network create elastic
```

Start Elasticsearch:

```bash
docker run --name elasticsearch --net elastic -p 9200:9200 -p 9300:9300 -e "discovery.type=single-node" -e "xpack.security.enabled=false" -e http.cors.enabled=true -e "http.cors.allow-origin='*'" -e http.cors.allow-headers=X-Requested-With,X-Auth-Token,Content-Type,Content-Length,Authorization -e http.cors.allow-credentials=true -e network.publish_host=localhost -e xpack.security.enabled=false docker.elastic.co/elasticsearch/elasticsearch:8.6.2
```

We are disabling security for this example, but you can read more about [securing Elasticsearch](https://www.elastic.co/guide/en/elasticsearch/reference/current/configuring-security.html) in the official documentation.

You will be able to access Elasticsearch at host `http://localhost:9200`.

### With Opensearch via Docker

Pull the Opensearch Docker image:

```bash
docker pull opensearchproject/opensearch:1.2.4
```

Start Opensearch:

```sh
docker run --name opensearch --rm -d -p 9200:9200 -e http.port=9200 -e discovery.type=single-node -e http.max_content_length=10MB -e http.cors.enabled=true -e "http.cors.allow-origin='*'" -e http.cors.allow-headers=X-Requested-With,X-Auth-Token,Content-Type,Content-Length,Authorization -e http.cors.allow-credentials=true opensearchproject/opensearch:1.2.4
```

You will be able to access Opensearch at host `http://localhost:9200`.

### Using Elastic Cloud

To connect to Elastic Cloud, you need to create an account and get your credentials. You can do this by following the instructions on the [Elastic Cloud website](https://www.elastic.co/cloud).

Once you have setup a deployment, do the following:

1. Go to the [Elastic Cloud console](https://cloud.elastic.co/).
2. Click on the deployment you want to connect to.
3. Locate either the Cloud Id or the Elasticsearch URL and copy it.
4. Paste the URL into the `connection.cloud_id` or `connection.host` field in the configuration object, within the Node app.

### Connecting with username:password

When you create a deployment, you will be provided a user & password. You can set the `connection.auth.username` and `connection.auth.password` fields in the configuration object.

```ts
const client = Client({
  connection: {
    cloud_id: "ELASTICSEARCH_CLOUD_ID",
    // or optionally the elasticsearch host
    // host: "ELASTICSEARCH_URL",
    auth: {
      username: "elastic",
      password: "changeme"
    }
  }
})
```

### Connecting with API key

Create an API key with `read` privileges for the index. 

You will need to pass an `Authorization` header to be able to create an API key.

```bash
curl --location --request POST 'http://localhost:9200/_security/api_key' \
--header 'Content-Type: application/json' \
-u 'elastic:changeme' \
--data-raw '{
  "name": "Elastic Search API Key",
  "role_descriptors": { 
    "role-a": {
      "cluster": ["all"],
      "index": [
        {
          "names": ["<index-name>"],
          "privileges": ["read"]
        }
      ]
    }
    
  }
}'
```

Copy the API key in `encoded` and paste it into the `connection.apiKey` field. 

```ts
const client = Client({
  connection: {
    host: "ELASTICSEARCH_URL",
    apiKey: "API_KEY"
  }
})
```

You can also do this within Kibana by going to `Stack Management > API Keys` and creating a new API key.

If Searchkit cannot connect to Elasticsearch, it will throw an error. You should be able to see the error in the terminal running the node API.

You can also switch on the `debug` [flag](/docs/api-documentation/api#debug-mode) in the configuration object, within the Node app, to see more detailed logs.

### Connecting to Elasticsearch with custom headers

If you are using Elasticsearch with a proxy, you may need to add custom headers to the request. You can do this by setting the `connection.headers` field in the configuration object, within the Node app.

```ts
const client = Client({
  connection: {
    host: "http://localhost:9200",
    headers: {
      "X-My-Header": "My-Value"
    }
  }
})
```

### Custom Transport

If all fails above, you can build your own custom transport. You can do so by implementing the `Transporter` interface.

```ts

import { ESTransporter } from 'searchkit'
import type { SearchRequest } from "searchkit"

class MyTransporter extends ESTransporter {
  async performNetworkRequest(requests: SearchRequest[]) {
    // you can use any http client here
    return fetch(`https://localhost:9200/_msearch`, {
      headers: {
        // Add custom headers here
      },
      body: this.createElasticsearchQueryFromRequest(requests),
      method: 'POST'
    })
  }
}

// then pass the custom transporter to the client
const client = Client({
  connection: new MyTransporter()
});
```

